home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
TeX 1995 July
/
TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO
/
macros
/
lollipop
/
lollipop.hqx
/
Lollipop Manual
/
comm.tex
< prev
next >
Wrap
Text File
|
1992-11-19
|
21KB
|
598 lines
% Comm.tex copyright 1992 Victor Eijkhout
%
\Chapter Commands
\Section[sec:counters] Counters
Counters can be declared explicitly by the user, but more often they
are defined automatically in some generic construct:
The \cs{Foo} defined by
\Ver>\DefineBar:Foo ...
counter:i ...
Stop<Rev
will have a counter that counts in roman lowercase, and which is
accessible as \refcs{FooCounter}. Everytime \cs{Foo} is used, this
counter is increased by one.
The use of the \opt{counter} option is described
in~\ref[sec:opt:counter].
Here are the commands for explicit manipulation of counters.
\SubSection[sec:counter:repr] Allocation and representation
A counter is created by for instance
\Ver>\NewCounter:Things<Rev
This will create control sequence \cs{ThingsCounter} that will print
the value of the counter.
The counter will usually be printed as an Arabic numeral, but other
counter representations can be specified by
\refcs{CounterRepresentation}. Here are their codes: \Description
\item 1
numeric
\item a
lowercase character
\item A
uppercase character
\item i
lowercase roman
\item I
lowercase roman
\>
for instance
\Ver>\CounterRepresentation:Things=i<Rev
will cause \cs{ThingsCounter} to print a lowercase Roman numeral.
However, a call such as
\Ver>\CounterRepresentation:Theorem=Lemma<Rev
will make the \cs{TheoremCounter} a synonym of an earlier created
\cs{LemmaCounter}
\SubSection Counter manipulation
The following commands can be used to manipulate counters, both when
they are created by hand using \refcs{NewCounter} and when they were
generated automatically in some generic construct:
Reset the counter to one:
\Ver>\StartCounter:things<Rev
Increase the counter by one:
\Ver>\StepCounter:things<Rev
Decrease the counter by one:
\Ver>\BackStepCounter:things<Rev
Set the counter to some specified value
\Ver>\SetCounter:things=5<Rev
\SubSection Counter hierarchies
Often counters are related to each other. For instance, when a new
section begins, the subsection counter has to be reset. The same may
be true for equation counters. In Lollipop such a relation is
indicated by a call to \refcs{GoverningCounter}, for instance
\Ver>\GoverningCounter:SubSection=Section<Rev
All of the counter manipulation commands applied to a governing
counter will cause all governed counters to be reset. Such a reset
also occurs if the counter was created in some generic construct.
For examples, see section~\ref[sec:head:examples].
\SubSection Referencing counters
All counters that are declared as part of a generic construct, or
explicitly through \refcs{NewCounter} automatically become the current
reference when they are altered. Thus \ver>\label[bar]> will make
\ver>\ref[bar]> refer to the value of the counter most recently
changed. The way the counter is referenced can be altered by the
\opt{label} option in generic constructs; see
section~\ref[sec:opt:label].
For generic constructs with a counter no explicit \refcs{label} commands
need to be given; such commands take an optional argument with the
label key:
\Ver>\Section[sec:examples] Examples<Rev
\SubSection Examples of counter usage
Items start at the value of one, so if a starting value of zero is
necessary, the following will work
\Ver>
\Enumerate \SetCounter:item=-1
\item ...<Rev
\ImpNote
\iSection The counter name
The \cs{count} register associated with a counter receives an internal
name:
\Ver>\def\counter@name#1{#1@C}<Rev
Also the following common abbreviations are provided:
\Ver>
\def\cs@counter@name#1{\csname#1@C\endcsname}
\def\counter@@name#1{\CSname{#1@C}}<Rev
\iSection Allocation and representation
The user command \refcs{NewCounter} allocates a counter plus an
associated `reset list':
\Ver>
\def\NewCounter:#1 {
\csarg\newtoks{#1@RL}
\csn #1@RL\ecs={}
\new@counter{#1}
}
\def\new@counter#1{
\new@@counter{#1}
\CounterRepresentation:{#1}=1
\StartCounter:{#1}
}
\def\CounterRepresentation:#1=#2 {
\if\UndefinedCS{\counter@name{#2}}%is deze teller een synoniem?
\represent@counter{#1}{#2}
\else \@SynonymCounter{#1}{#2}
\fi}
\def\represent@counter#1#2{
\edef\cs@e{@\if#2iroman\else
\if#2IRoman\else \if#2alcascii\else
\if#2Aucascii\else arabic\fi\fi\fi\fi}
\csarg\edef{\counter@repr{#1}}{\CSname{\cs@e}}
\csarg\edef{#1Counter}%
{\CSname{\counter@repr{#1}}\counter@@name{#1}}
}
\def\@SynonymCounter#1#2{\edef\cs@b{%
\nxp\let\counter@@name{#1}=\counter@@name{#2}
\nxp\let\CSname{#1Counter}=\CSname{#2Counter}
\nxp\let\CSname{#1@RL}=\CSname{#2@RL}}
\cs@b
}
\@GenericOption{sharecounter}
{\CounterRepresentation:\@name=#1 }<Rev
\iSection Governing and resetting
A counter can be defined as being governed by another counter;
whenever the other counter is manipulated, this counter is reset.
The implementation is through `reset lists': every counter is added to
the reset list of its governing counter, and whenever a counter is
altered, everything in its reset list is reset.
\Ver>
\def\GoverningCounter:#1=#2 {\if\UndefinedCS{#2@RL}
\Emessage{No counter defined for `#2'}
\else\append@to@list{#2@RL}{\\#1;}\fi}
\def\reset@subordinates#1{%
\def\\##1;{\start@counter{##1}}%
\the\csname #1@RL\endcsname \let\\=\relax}<Rev
The command \cs{reset@subordinates} is executed by all user level
commands:
\Ver>
\def\StartCounter:#1 {\handle@user@counter{#1}{start}{}}
\def\StepCounter:#1 {\handle@user@counter{#1}{step}{}}
\def\BackStepCounter:#1 {\handle@user@counter{#1}{back@step}{}}
\def\SetCounter:#1=#2 {\handle@user@counter{#1}{set}{#2}}
\def\handle@user@counter#1#2#3%
{\if\UndefinedCS{\counter@name{#1}}
\Wmessage{Unknown counter: #1}
\else \csarg\global{#2@counter}{#1}{#3}%
\reset@subordinates{#1}\define@reference{#1}%
\fi}<Rev
The system level commands have no further complications.
\Ver>
\def\step@counter#1%
{\increase@value{\counter@name{#1}}\@ne}
\def\back@step@counter#1%
{\increase@value{\counter@name{#1}}\m@ne}
\def\start@counter#1%
{\set@value{\counter@name{#1}}\z@}
\def\set@counter#1#2%
{\set@value{\counter@name{#1}}{#2}\relax}<Rev
\ImpNoteStop
\Section[sec:font] Font selection
In \Lollipop, choosing a font is done through three parameters:
\Description\item Typeface
A collection of related styles and sizes. The typeface is set by the
command \refcs{Typeface}.
\item Style
Italic, bold, roman, typewriter. You know. The style is set by the
command \refcs{Style}.
\item PointSize
The size of a font in typographical points ($72.27$ per inch).
The pointsize is set by the command \refcs{PointSize}.
\>
The most common change of font is a change in style. Therefore,
issuing a command such as \Ver>\Style:bold<Rev immediately changes
the font to the bold of the current typeface in the current pointsize.
However, issuing a command such as \Ver>\Typeface:GoudyOldStyle<Rev
or \Ver>\PointSize:28<Rev will not change the font, since such
changes are usually accompanied by a change in style. In case that an
immediate switch is necessary, the command
\refcs{SetFont} can be given.
This evaluates the current value of the typeface, style, and
pointsize commands, and sets the font accordingly.
A number of typeface names have been predefined in \Lollipop,
however, in order to print them your printer (software) must have them
available.
\Example
\SerifFace \PointSize:12
\Style:roman This \Style:italic sentence \PointSize:10 has
\SetFont way \SansFace \Style:roman too \SetFont many
\PointSize:12 \SetFont font \Style:bold changes.
\ExampleStop
(The commands \cs{SerifFace} and \cs{SansFace} are defined in
the master file of this manual, and serve to make this manual
formattable on any system.)
\SubSection Relative size changes
Apart from setting the pointsize explicitly, it is also possibly to
make size changes relative to the current size. For instance,
\refcs{PointSizeLarger} and \refcs{PointSizeSmaller} with an optional
argument indicating the size of the change can be used. These
commands are not cumulative.
\Example
\SerifFace
\PointSize:9 \SetFont Every once in a while,\SaveFont
\PointSizeLarger[2] shouting \PointSizeLarger helps.
\PointSizeSmaller[2]But most of the times it doesn't.
\RestoreFont Unfortunately.
\ExampleStop
Similar to the changes in mathematics mode to script and scriptscript
size, the same relative changes are available in text mode through
the control sequences \refcs{script} and \refcs{scriptscript}.
The control
sequence \refcs{normal} can be used to restore the default size.
Here is one application of such relative changes:
\Ver>
L\kern -.3em\raise .35ex\hbox {\script A}\kern -.1em\TeX<Rev
which gives definition of the \LaTeX\ logo that is independent
of typeface, size and style.
The relative sizes of script and scriptscript fonts are by default at
$70\%$ and $50\%$, but they can be set explicitly by
\Ver>\PointSizeScriptSizes:10=10,7,5<Rev
This also gives the possibility to have the \cs{normal} size to be
different from the surrounding pointsize.
\SubSection Typeface definition
Defining a typeface means telling \Lollipop\ how the external font
name, that is, the name of the \n{tfm} file, is to be constructed from
the internal parameters. The command \refcs{DefineTypeface} takes four
parameters and an optional fifth. The parameters are in sequence
\Enumerate\item The internal name of the typeface: the name that is
given to the \cs{Typeface} command.
\item The root of the external file name. It is assumed that all
font names of different styles and sizes are constructed by appending
characters to this base.
\item Suffixes corresponding to the styles that are available.
\item Suffixes corresponding to the sizes that are available.
\>
Here is the definition of the Computer Modern typeface:
\Ver>
\DefineTypeface{ComputerModern}{cm}
{roman:r; slant:sl; italic:ti; mitalic:mi; bold:bx; tty:tt;
default:r;}
{<6:5; <7:6; <8:7; <9:8; <10:9; <11:10;
<12:10 \scaled\magstephalf;
<14:10 \scaled\magstep1; <16:10 \scaled\magstep2;
<20:10 \scaled\magstep3; >19:10 \scaled\magstep4;
default:10;}<Rev
Actually, not all combinations of styles and sizes are available.
That's where the optional argument comes in. This argument can be
used to specify with \TeX\ conditionals exceptional style/size
combinations. Here some trickery is needed: internally the size is
stored in \cs{F@size}, and in order to use this parameter we need to
make the at-sign a letter temporarily.
\Ver>\makeatletter
\DefineTypeface{Compu ...
...
default:10;}
[\ifStyle:italic \ifnum\F@size<7 ti7\fi\fi
\ifStyle:tty \ifnum\F@size<8 tt8\fi\fi]<Rev
For other typefaces specifying the size suffix may be much easier
than for Computer Modern. For instance, here is the definition of the
PostScript Helvetica typeface.
\Ver>\makeatletter
\DefineTypeface{psHelvetica}{helv}
{roman:; italic:i; mitalic:i; bold:b; default:;}
{default: at \F@size pt;}
\makeatother<Rev
\SubSection Math fonts
Switching styles in math mode should be possible:
$${\Style:bold x\Style:roman y}z$$
\SubSection Other font matters
The combination \refcs{SaveFont} with a subsequent
\refcs{RestoreFont} can
be used to save and restore the current font.
An abbreviation for a font can be defined by
\Ver>\DefineFont:name=face,size,style<Rev
Even if you don't use Computer Modern as your main typeface, the
typewriter style is not bad, so a control sequence
\Ver>
\def\tt{\Typeface:ComputerModern \Style:tty }<Rev
has been given that makes \refcs{tt} always refer to the
\n{cmtt} fonts. You're at liberty to change this, of course.
\Section Baselineskip
Corresponding to a font size usually the baseline skip has to change.
By default a fixed ratio of~$1.2$ for this is taken, for instance
using a 12~point baseline skip for 10~point fonts. Changing the ratio
can be done by
\Ver>\BaselineSkipPointSizeRatio:1.3<Rev
If only for some specific size the baseline skip has to deviate from
the default ratio, then this can be set by
\Ver>\SetPointSizeBaselineSkip:9=12<Rev
\Section[sec:indent:control] Indentation Control
\SubSection To indent or not to indent
In most documents there is a general rule that all paragraphs indent
unless a certain condition, or that they do not indent unless certain
special conditions hold. For \Lollipop\ documents this is determined
by the command \refcs{AlwaysIndent}, with values \n{yes}/\n{no}.
To override this default setting a command \refcs{Indent}
(with values \n{yes}/\n{no}) exists, but that is mostly useful as an
option in generic constructs, and even there it will not be used much.
See section~\ref[sec:opt:indent] for options relating to indentation.
Important: never set \cs{parindent} to zero. Preventing indentation
globally should be done through \ver>\AlwaysIndent:no>.
\SubSection[sec:basic-indent] Basic indent
There is a quantity \refcs{basicindent} that is used on the first
indentation level (see the next section for an explanation of these
levels). At the start of a document it is set to the then current
value of \cs{parindent}. You can override that by
\refcs{BasicIndentIsSet}: give
\Ver>\BasicIndentIsSet:no<Rev before the \cs{Start} command.
This way, setting \cs{parindent} in the style definition controls the
indentation in the whole document.
\SubSection Indentation levels; indentation size
When \Lollipop\ decides that text should be indented, it refers to a
list of indentations for the exact amount. This list contains
indentation amounts for each `level' of indentation: initially the
level is one, and if you nest constructs that indent (for instance
using a list inside a list) the level goes up one step per nested
construct.
By
default the indentation on different levels is a fraction of the
\cs{basicindent}. Thus you can regulate the indentation on
all levels simultaneously by resetting the \cs{basicindent}.
\Example
\Distance:basicindent=15pt
\DefineList:TestList item:left itemCounter item:stop Stop
\TestList\item Level one \TestList\item Level two
\TestList\item Level three\>]
\Distance:basicindent=25pt
\TestList\item Level one \TestList\item Level two
\TestList\item Level three\>]
\ExampleStop
The amount of
indentation on a certain level can be set explicitly with
\refcs{LevelIndent}.
\Example
\Distance:basicindent=15pt
\LevelIndent:2=20pt
\DefineList:TestList item:left itemCounter item:stop Stop
\TestList\item Level one \TestList\item Level two
\TestList\item Level three\>]
\ExampleStop
\SubSection Manipulating the indentation level
Every once in a while it can be useful to move to a next indentation
level, or to return to a previous level. For this
the two commands \refcs{PushIndentLevel} and \refcs{PopIndentLevel} are
available. One application is for `interrupted lists':
\Example
\Itemize\item One
{\par\PopIndentLevel Interrupted text!\par}
\item Two\>
\ExampleStop
See chapter~\ref[chap:external-files] for examples of the use of
\cs{PushIndentLevel}
\Section Margins
By default, \Lollipop\ tries to keep straight margins. You can change
its mind about that by
\Ver>\FlushRight:no \FlushLeft:no<Rev
If the margins are not flush, the stretchable white space used
is \refcs{rightmarginstretch} and \refcs{leftmarginstretch}.
\Section White Space
White space can be indicated by \refcs{hwhite} and \refcs{vwhite}.
They are often useful in style definitions. Use:
\Ver>\vwhite:15pt<Rev
or \Ver>\hwhite:{15pt minus 3pt}<Rev
for stretch and shrink. The command \refcs{white} is independent
of the mode, and it expands to \cs{hwhite} or \cs{vwhite}
depending on the prevailing mode of \TeX.
The command \refcs{fillup} is mostly useful in style definitions:
it tries to fill up as much white space as is possible.
For instance
\Ver> line:start litteral:foo fillup litteral:bar line:stop<Rev
will push \n{foo} and \n{bar} as far apart as is possibly
within the margins.
\ImpNote
All three control sequences \cs{white}, \cs{hwhite}, \cs{vwhite}
have internal equivalents, for instance
\Ver>\def\white:#1 {\@white{#1}}<Rev
\ImpNoteStop
\Section[sec:com:distance] Distances
The command \refcs{Distance} can be used
to declare a name for a certain
distance, or in more correct \TeX nical lingo, for a certain piece of
glue. For instance, declaring that
\Ver>\Distance:oneline=15pt<Rev
means that you can specify in some constructs
\Ver>\DefineFoo:Bar whitebefore:oneline whiteafter:oneline<Rev
If you change your mind later about the value of \n{oneline} you only
need to change one line in the style definition.
Since the second parameter of \cs{Distance} is bounded by a space (or
the line end, whatever comes first), you can specify stretchable
distances by enclosing \n{plus} and \n{minus} parts in braces:
\Ver>\Distance:oneline={15pt plus 2pt minus 3pt}<Rev
The effect of \cs{Distance} is global. Let me know if you don't
like it.
\SubSection Distance synonyms
Another use of \cs{Distance} is to define one distance as a synonym
of another. This may come in handy if you use some basic distance,
such as \n{oneline} for several purposes. Example: if you specify
\Ver>\Distance:whitebefore=oneline<Rev
than the whitespace before a construct will be taken to be
\n{oneline} if you don't use the \opt{whitebefore} option explicitly.
\SubSection[sec:adapt-distance] Adaptive distances
Suppose you want to declare a section heading as
\Ver>\DefineHeading:Section ...
block:start [...] fillupto:widelabel title<Rev
where \cs{widelabel} is the width of the widest label that
occurs in your document. This requires just a tad of \TeX\
programming. Just copy the details from the example below, which is
the definition of \cs{Section} in this manual.
By declaring something a \refcs{AdaptiveDistance} instead of just
\cs{Distance} its value gets written to the \file{.aux} file at the
end of the run, and restored in the next run. The second argument is
simply the default value, in case you don't have an auxiliary file
yet.
\Ver>\AdaptiveDistance:WidestLabel=15pt
\def\MeasureLabel{\ifdim\BlockWidth>\WidestLabel
\global\WidestLabel\BlockWidth\fi}
\DefineHeading:Section
whitebefore:{20pt plus 2pt} whiteafter:14pt
line:start PointSize:14 Style:italic
block:start block:start ChapterCounter . SectionCounter
Spaces:1 block:stop MeasureLabel
fillupto:WidestLabel
title line:stop
external:contents title external:stop
label:start ChapterCounter . SectionCounter label:stop
Stop<Rev
Note how two nested blocks are used: the first is to measure the
label, and the width is written to the adaptive distance by means of
a small macro; the second block is to fill out the white space.
If you want the paragraph indentation to depend on this adaptive
width, you can give
\Ver>\StartCommand{\Distance:parindent=WidestLabel }<Rev
to set \cs{parindent} at the start of the document.
See section~\ref[sec:doc-start-stop] and~\ref[sec:basic-indent].
\Section[sec:InputFile] Input Files
Parts of a document can be loaded by
\Ver>\InputFile:parta
\InputFile:partb<Rev
et cetera. A~document part loaded by \refcs{InputFile} always starts
on a new page. In section~\ref[sec:ref-local] it was already
explained how local references for such files can be created.
Perhaps most importantly, loading files this way provides a form of
error checking; \Lollipop\ checks at the end of such a file whether all
used constructs are balanced properly.
\Section[sec:tests] Tests
Users can define tests:
\Ver>\DefineTest:SomethingTheMatter<Rev
which are set like any other test:
\Ver>\SomethingTheMatter:yes<Rev
or \Ver>\SomethingTheMatter:no<Rev
Tests can be used as \Ver>\ifSomethingTheMatter ... \else ... \fi<Rev
Like any other conditional, test can be used inside constructs.
\Ver>\DefineFoo:Bar [...]
ifSomethingTheMatter [...] fi
[...] Stop<Rev
\Section Goodies
\SubSection[sec:everypar] \cs{everypar}
The \TeX\ primitive \cs{everypar} should note be used any more.
Instead use the command \refcs{EveryParagraph} as if you are setting
a token list:
\Ver>\EveryParagraph{ ... }<Rev
\SubSection Allocation
The commands \refcs{SaveAlloc} and subsequent \refcs{RestoreAlloc} save and
reset the internal \TeX\ allocation counters.
\ImpNote Obscure goodies
\iSection[imp:new:dummy] Dummy commands
For purposes such as termination of an argument it is usefule to have
control sequences that have a meaning different from any other
control sequence. The command \refcs{NewDummy} gives such control
sequences. The call \ver>\NewDummy{some}> defines \cs{some}, or gives
an error msg at redefinition.
\ImpNoteStop